🟡 Heimdall Review Status

@ohld is attempting to deploy a commit to the Coinbase Team on Vercel.

A member of the Team first needs to authorize it.

Really excited to see TON getting a proper x402 spec — the W5/internal_signed <=> EIP-3009 mapping is elegant. A few things I noticed that might be worth addressing before the implementation PR:

1. >= vs == and the exact scheme semantics
scheme_exact.md requires amount MUST equal requirements.amount exactly, but the TON addition uses >= in both the index and the spec body (verification rules §1 and §3). I'm guessing this is because the relay commission is bundled into the same jetton_transfer, pushing the gross transfer slightly above requirements.amount — but if so, it probably needs to be called out explicitly, and some bound on overpayment defined. Otherwise >= requirements.amount could pass for any amount, which feels at odds with the scheme name.

2. stateInit (seqno == 0) — worth adding a code hash check
Step 7 mentions including stateInit for new wallet deployments, but there's no rule telling facilitators to verify the deployed contract is actually a W5 wallet. A malicious client could potentially submit a stateInit for an arbitrary contract. Might be worth adding: facilitator MUST verify the code hash matches the canonical W5 v5r1 hash before accepting a seqno-0 payload.

3. Relay commission amount is undefined
Verification rule 4 says the W5 message "MUST NOT contain additional unrelated actions beyond the payment transfer and relay commission" — but the commission amount isn't communicated anywhere in PaymentRequirements or PaymentPayload. Without it, how does a facilitator distinguish a valid commission from an inflated one? Maybe extra.relayCommission in PaymentRequirements, or a specified max ratio?

Thanks for the thorough review, these are all great catches.

1. >= → == (exact amount)

You're right — >= was wrong here. The relay commission on TON is a separate jetton_transfer action in the W5 batch, not bundled into the payment transfer amount. So the payment to the recipient is exactly requirements.amount, and the commission goes to extra.relayAddress independently. Fixed both the spec and the index to use strict equality, matching SVM/Stellar/EVM.

2. stateInit code hash check

Good call. I didn't want to hardcode a specific hash in the spec since W5 has revisions (v5r1, potentially v5r2) and a hardcoded hash would become outdated when TON Foundation ships a new version. Instead I added: facilitator MUST verify that the contract code in stateInit matches a known W5 wallet contract, and SHOULD maintain an allowlist of accepted wallet code hashes. This follows how SVM handles program IDs — the validation logic is in the facilitator implementation, not frozen in the spec.

3. Relay commission bounds

Added extra.maxRelayCommission (optional) to PaymentRequirements. When the resource server sets it, the facilitator rejects W5 batches where the commission transfer exceeds that cap. When absent, the facilitator applies its own policy. This gives resource servers explicit control without hardcoding a ratio that would break as gas prices change.

Also tightened rule §4: the W5 message must contain exactly two actions (payment transfer + optional commission transfer), anything else is rejected.

All changes in the latest commit + updated the demo repo to enforce exact amount matching (30/30 tests passing).

Thanks a lot for putting this together @ohld!

Notified the core team to review. Please be aware that we currently have a lot of pending/incoming requests, so it might take a bit until we can get back to you, thanks for your patience 🙏

While we wait for the spec review, I created a facilitator for TON

https://github.com/ohld/x402-ton-facilitator

And our community also implemented one: https://github.com/TONresistor/x402-ton

We'll start implementing all SDKs as well.

We implemented this spec in production with x402-ton (https://github.com/TONresistor/x402-ton).

Two findings from our integration:

Commission discovery at boot: The spec recommends discovering commission via /v2/gasless/estimate, but this endpoint requires a real unsigned BOC. A dummy/sample BOC always returns 400. We ended up using a config fallback (MAX_RELAY_COMMISSION) when the estimate is unavailable.

Native TON support: Our implementation supports both USDT gasless (internal auth via TONAPI) and native TON direct broadcast (external auth). The PR describes the jetton path only. We treat native TON as an additive superset since payers with TON already have gas and don't need the gasless relay.

Live facilitator: https://x402.resistance.dog
npm: x402ton@2.0.0

Hi @ohld, thanks again for your contribution! This a great start and the spec is well written and structured.

Please have a look at my comments above, there a 2 main points to clarify:

1. relayer model, in particular clearly separating the roles of facilitator vs relayer (or explicitly stating that the facilitator is the relayer if thats the case)
2. state requirement on the facilitator

Would it be possible to let the facilitator actually sponsor the gas aligning the flow with the existing mechanism for other chains?

Concretely I would suggest the following (if technical possible) that would significantly simplify the spec:

• Client signs ONLY one jetton_transfer to payTo
• The facilitator appends the jetton_transfer to relayAddress and pays the gas (ie not the client)
• Server and client would not need to know anything about the relayer like relayAddress or maxRelayCommission, all handled by the facilitator
• The facilitator could either outsource the relay to an external service (as long as it pays for it) OR implement its own relay logic and charging the client no relay fee OR just submit the tx directly and paying gas in TON (as long as it pays for it). This could remain an implementation detail of the facilitator
• The facilitator is compensated by the server out of band as for the other networks

Updated spec to self-relay architecture. Tested with 7 mainnet USDT payments.

Key change: Facilitator = relay. No commission. Client signs 1 jetton_transfer,
facilitator wraps + sponsors gas (~$0.04/tx).

Review comments:

1. Gas sponsorship (line 22) — Facilitator pays ~0.013 TON/tx. Zero client cost.
2. Verify required (line 36) — Fixed. Now REQUIRED.
   3-4. Facilitator vs relayer (lines 68-69) — One entity. relayAddress removed.
3. Relay fee (line 69) — None. Client sends exact amount.
4. Extra fields (line 71) — Removed assetDecimals/assetSymbol. Only facilitatorUrl remains.
5. Transfer count (line 166) — Exactly 1. Enforced in verification rule 3.
6. Statefulness (line 174) — In-memory BoC hash dedup, 600s TTL. Same as SVM pattern.
   9-13. Relay fee bounds, who pays — N/A, no relay fee exists.

cc @nicholasrice — you've been working on TON support too (#1495)

One thing worth flagging: TON gas is 0.013 TON ($0.04) per jetton transfer, which is 20-40x more than Base ($0.001) or Solana ($0.0005). This makes the "facilitator absorbs gas" model harder to sustain long-term compared to EVM/SVM.

For now my facilitator covers gas from personal funds, same as the free facilitators on other chains. But for production sustainability, facilitators would likely either bill merchants out-of-band (the standard x402 model) or include an optional commission transfer in the /prepare response — the client sees and signs everything, fully transparent. Per @phdargen's earlier guidance, relay economics are an implementation detail of the facilitator, so this stays outside the spec itself.

Worth noting: TON Foundation could sponsor a public facilitator to bootstrap adoption (similar to Coinbase's CDP facilitator on Base). And realistically, TON x402 makes more sense for $0.10+ payments where gas overhead is proportional.

None of this changes the spec — just providing context on operational economics.

Hey, @phdargen!

We have updated our commits to be verified